<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	
	<head>
		<meta http-equiv="Content-Language" content="en-gb" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="description" content="Transformations" />
		<title>PDF Graphics .NET documentation - Transformations</title>
		<link rel="stylesheet" href="../style/Help.css" type="text/css" />
	
	</head>
	
	<body>
		<div class="navigator">
			<span>
				<strong>PDF Graphics .NET</strong> :: <a href="..\Index.html">Help</a> :: <a href="..\Painting_graphics.html">Painting graphics</a> :: Transformations
			</span>
		</div>
		
		<h1>Transformations</h1>
							
		<p>
			Use transformations to alter graphics operations by scaling, moving or rotating them. Multiple transformations can be
			applied to graphics. This section describes the possible transformation types, and how to combine them to achieve
			the effects you need. It covers the following topics:
			<ul>
				<li><a href="#TransformationTypes">Transformation types</a></li>
				<li><a href="#Combining">Combining transformations</a></li>
				<li><a href="#State">Preserving and restoring state</a></li>
			</ul>			
		</p>
			
		<h2><a name="TransformationTypes"></a>Transformation types</h2>

		<p>
			Below is a list of the transformations supported by PDF Graphics .NET:
		</p>
			
		<h3>Translation (moving graphics)</h3>
		
		<p>
			<emp>Translation</emp> results in graphics operations being offset by specified amounts along the X and Y axes.
			To perform a translation, use the <span class="code">TranslateTransform</span> method on the <span class="code">Graphics</span>
			instance.<br/>
			In the example below, a circle is painted onto the page. A translation is then applied, and the same circle painted again;
			the second circle appears to the right of, and slightly below, the first.
		</p>
			
		<div class="sampleCode">Rectangle bounds = new Rectangle(10, 10, 50, 50);
g.FillEllipse(Rgb.BlueBrush, bounds);
g.DrawEllipse(Rgb.RedPen, bounds);

g.TransformTranslate(75, 25);
g.FillEllipse(Rgb.BlueBrush, bounds);
g.DrawEllipse(Rgb.RedPen, bounds);</div>

		<img src="../images/Transform_Translate.jpg" />
		
		<h3>Scaling</h3>

		<p>
			After applying a scaling transformation, all subsequent graphics are scaled by the specified ratio along the axes.
			Use the <span class="code">TranslateScale</span> method to perform the scaling operation.
			In the following example, a rectangle is drawn, and then a transformation is applied that scales graphics to half their size.
			The rectangle is then drawn again.
		</p>			
		
		<div class="sampleCode">Rectangle bounds = new Rectangle(10, 10, 100, 100);
g.FillRectangle(Rgb.CyanBrush, bounds);
g.DrawRectangle(new Pen(Rgb.Red, 0.25f, new int[] {2,0}, 0), bounds);

g.TransformScale(0.5f, 0.5f);
g.FillRectangle(Rgb.BlueBrush, bounds);
g.DrawRectangle(Rgb.RedPen, bounds);</div>

		<img src="../images/Transform_Scale.jpg" />
			
		<p>
			Note that the smaller rectangle is also positioned slightly to the left and above the larger one; it is painted at coordinate
			<span class="code">(10,10)</span>, which is scaled down to <span class="code">(5,5)</span>. Scaling affects not only the size of painted graphics but also their position.
		</p>
		
		<h3>Rotation</h3>
		
		<p>
			Rotation of graphics is performed relative to the top-left corner of the page, in counter-clockwise fashion. The
			<span class="code">TranslateRotate</span> method performs a rotation transformation, with the angle specified in
			radians, counter-clockwise. In the example below, text is drawn at various angles.
		</p>
				
		<div class="sampleCode">Font font = new Font("Times New Roman");
g.TransformTranslate(100, 100);
for (int i = 0; i < 16; i++)
{
    g.DrawString(Rgb.BlackBrush, "Rotated text", font, 16f, 20, 0);
    g.TransformRotate(-0.4f);
}</div>

		<img src="../images/Transform_Rotate.jpg" />
			
		<p>
			To ensure that the rotated text fits on the page, it is first translated 100 points towards the center of the page.
			This is an example of combining transformations, which will be covered later in this section.
		</p>
			
		<h3>Skewing</h3>
		
		<p>
			Skewing can be seen as pulling on one side of the graphics coordinate space; either pulling the right-hand side up, or pulling the bottom
			side towards the left. The result is that the coordinate space appears lifted up on one side, or falling over to another. It is
			best explained through an example. See the code below:
		</p>
			
		<div class="sampleCode">bounds = new Rectangle(10, 10, 50, 70);

g.FillRectangle(Rgb.GreenBrush, bounds);

g.TransformTranslate(100, 0);

g.BeginContainer();
g.FillRectangle(Rgb.GreenBrush, bounds);
g.TransformSkew(0.2f, 0);
g.FillRectangle(Rgb.DarkGreenBrush, bounds);
g.EndContainer();

g.TransformTranslate(100, 0);

g.FillRectangle(Rgb.GreenBrush, bounds);
g.TransformSkew(0, 0.2f);
g.FillRectangle(Rgb.DarkGreenBrush, bounds);</div>	

		<p>
			A green rectangle is painted onto the page. Then, the coordinate space is skewed along the X axis. The result can be seen in the second
			picture, where the X axis of the dark rectangle is no longer horizontal; it's being pulled up. In the third picture, the Y axis is
			skewed. The rectangle appears to fall over to one side.
		</p>

		<img src="../images/Transform_Sheer.jpg" />

		<p>
			This example also shows how to save and restore the current graphics state; more on that further down. For a full explanation of
			graphics state preservation, see <a href="Dont know.html">Graphics state</a>.
		</p>			
		
		<h3>Free transform</h3>
		
		<p>
			All of the above transformations (translation, scaling, rotation and skewing) are essentially the same; they alter the current
			<em>coordinate space matrix</em> of the graphics target (page or stencil). Matrices have traditionally been used to represent
			common graphics transformations. If required, a free-form transformation can be performed by supplying a suitable
			matrix to the <span class="code">Transform</span> method. For more information, see the <a href="../reference/matrix.html">Matrix</a>
			class reference documentation.
		</p>
			
		<p>
			Coverage of graphics transformations through matrices is beyond the scope of this section, but numerous examples can be found
			on-line. The Adobe PDF specification also includes an explanation of graphics coordinate transformation.
		</p>
		
		<h2><a name="Combining"></a>Combining transformations</h2>
		
		<p>
			Transformations can be combined. When combining, the order of transformations is important; scaling followed by a
			rotation is different from a rotation followed by scaling. Take the following example:
		</p>
		
		<div class="sampleCode">bounds = new Rectangle(10, 10, 50, 70);

g.TransformTranslate(100, 100);
g.TransformRotate((float)Math.PI / 8);
g.FillRectangle(Rgb.GreenBrush, bounds);

g.NewPage();

g.TransformRotate((float)Math.PI / 8);
g.TransformTranslate(100, 100);
g.FillRectangle(Rgb.GreenBrush, bounds);</div>	
		
		<p>
			This creates two pages. On the first page, the green rectangle is moved 100 points down and to the right, and then rotated.
			On the second page the coordinate space is rotated first, and then moved down and to the right.
		</p>
			
		<h2><a name="State"></a>Preserving and restoring state</h2>

		<p>
			Coordinate transformations remain in effect after drawing operations. To reset the coordinate system, use the
			<span class="code">BeginContainer</span> and <span class="code">EndContainer</span> methods. These methods
			store the current state of the transformation matrix and restore a previous state, respectively.
		<p>
		
		<p>
			Storing and restoring state is not limited to a single level; numerous states can be stacked with successive
			calls to <span class="code">BeginContainer</span>. Each <span class="code">EndContainer</span> call restores the
			previous state until the coordinate space has been reset to its initial values.
		</p>
		
		<p>
			In the following example, a number of squares is painted onto the page, using a transformation for each.
			The transformations are then restored, and the rectangles outlined:
		</p>
			
		<div class="sampleCode">bounds = new Rectangle(-50, -50, 100, 100);

g.TransformTranslate(200, 200);

g.FillRectangle(Rgb.YellowBrush, bounds);

g.BeginContainer();
g.TransformScale(0.7f, 0.7f);
g.FillRectangle(Rgb.GreenBrush, bounds);

g.BeginContainer();
g.TransformScale(0.7f, 0.7f);
g.FillRectangle(Rgb.CyanBrush, bounds);

g.BeginContainer();
g.TransformScale(0.7f, 0.7f);
g.FillRectangle(Rgb.BlueBrush, bounds);

g.DrawRectangle(Rgb.RedPen, bounds);
g.EndContainer();

g.DrawRectangle(Rgb.RedPen, bounds);
g.EndContainer();

g.DrawRectangle(Rgb.RedPen, bounds);
g.EndContainer();

g.DrawRectangle(Rgb.RedPen, bounds);</div>			
		
		<img src="../images/Transform_States.jpg" />
		
		<h3><strong>Navigation options:</strong></h3>
		<p><a href="Images_stencils.html">&lt; Images and stencils</a> | <a href="Gradients.html">Gradients &gt;</a>
		
	</body>
	
</html>